Kurzreferenz · REST-API · Datenzugriff

Sortierung, Filterung, Pagination & API-Antworten

Kompaktes Cheatsheet für die Arbeit mit REST-APIs: Query-Parameter lesen, Daten gezielt abrufen, Antworten bewerten und typische Fehler sauber einordnen.

GET-ParameterFilterSortierungPaginationStatuscodesJSON-Antworten

1. Query-Parameter lesen

Query-Parameter stehen nach dem Fragezeichen ? in einer URL. Mehrere Parameter werden mit & verbunden.

GET /produkte?kategorie=hardware&sort=preis&order=asc&page=2&limit=10
TeilBedeutung
/produkteRessource: Es geht um Produktdaten.
kategorie=hardwareFilter: Nur Produkte aus der Kategorie Hardware.
sort=preisSortierfeld: Die Liste wird nach Preis sortiert.
order=ascSortierrichtung: aufsteigend.
page=2Seite 2 der Ergebnisliste.
limit=10Maximal 10 Einträge pro Seite.
Hinweis: Query-Parameter verändern meist die Darstellung oder Auswahl einer Liste. Die Ressource selbst bleibt gleich.

2. Filterung

Filter begrenzen eine Ergebnisliste auf Datensätze, die bestimmte Bedingungen erfüllen.

GET /produkte?kategorie=zubehoer
GET /produkte?aktiv=true
GET /produkte?minPreis=10&maxPreis=200
GET /produkte?lagerbestandUnter=5

Typische Filterarten

FilterBeispielBedeutung
Textgleichheitkategorie=zubehoerNur eine bestimmte Kategorie.
Booleanaktiv=trueNur aktive Produkte.
ZahlenbereichminPreis=10&maxPreis=200Nur Produkte im Preisbereich.
BestandsgrenzelagerbestandUnter=5Nur Produkte mit niedrigem Lagerbestand.
Hinweis: Filter sollten klar benannt sein. minPreis ist verständlicher als p1.

3. Sortierung

Sortierung legt fest, in welcher Reihenfolge Ergebnisse angezeigt werden.

GET /produkte?sort=name&order=asc
GET /produkte?sort=preis&order=desc
GET /produkte?sort=lagerbestand&order=asc
ParameterWertBedeutung
sortnameSortiere nach Produktname.
sortpreisSortiere nach Preis.
orderascAufsteigend: A–Z oder klein nach groß.
orderdescAbsteigend: Z–A oder groß nach klein.
Hinweis: Wird nach Preis sortiert, muss preis als Zahl gespeichert sein. Ein Textfeld würde z. B. 100 vor 20 sortieren können.

4. Pagination

Pagination teilt große Ergebnislisten in kleinere Seiten auf. Dadurch werden API-Antworten schneller und übersichtlicher.

Client fragt an
page=1&limit=10
API filtert
passende Datensätze werden gesucht
API schneidet Liste
nur 10 Einträge werden geliefert
Client navigiert
nächste Seite per page=2
GET /produkte?page=3&limit=20

Das bedeutet meist: Gib die dritte Seite zurück, mit maximal 20 Produkten pro Seite.

Antwort mit Metadaten

{
  "data": [
    { "id": 41, "name": "Tastatur", "preis": 29.99 }
  ],
  "pagination": {
    "page": 3,
    "limit": 20,
    "totalItems": 87,
    "totalPages": 5,
    "hasNextPage": true,
    "hasPreviousPage": true
  }
}

5. Gute API-Antworten

Eine gute Antwort ist maschinenlesbar, konsistent und enthält bei Listen oft Zusatzinformationen.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": 3,
      "name": "Monitor",
      "kategorie": "Hardware",
      "preis": 199.99,
      "lagerbestand": 7,
      "aktiv": true
    }
  ],
  "count": 1
}
Hinweis: Einheitliche Feldnamen helfen Clients, Antworten zuverlässig zu verarbeiten.

6. Fehlerantworten

Fehler sollten nicht nur technisch korrekt, sondern auch verständlich sein.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "INVALID_QUERY_PARAMETER",
  "message": "Der Parameter 'limit' muss eine Zahl zwischen 1 und 100 sein.",
  "details": {
    "parameter": "limit",
    "received": "abc"
  }
}
StatuscodeSituation
200 OKListe oder einzelner Datensatz erfolgreich geliefert.
201 CreatedNeuer Datensatz wurde erfolgreich angelegt.
204 No ContentAktion erfolgreich, aber keine Antwortdaten nötig.
400 Bad RequestUngültige Anfrage, z. B. falscher Parameter.
404 Not FoundRessource existiert nicht.

7. Parameter kombinieren

Filter, Sortierung und Pagination können in einer Anfrage kombiniert werden.

GET /produkte?kategorie=hardware&aktiv=true&sort=preis&order=desc&page=1&limit=5

Lesart:

  1. Suche Produkte.
  2. Nur Kategorie Hardware.
  3. Nur aktive Produkte.
  4. Sortiere nach Preis, teuer zuerst.
  5. Gib die erste Seite mit maximal fünf Produkten zurück.
Hinweis: In der Verarbeitung kommt häufig zuerst die Filterung, dann die Sortierung, dann die Pagination.

8. Validierung von Parametern

Nicht jeder Parameterwert ist sinnvoll. Eine API sollte Eingaben prüfen.

AnfrageProblemMögliche Antwort
?limit=abcKeine Zahl400 Bad Request
?page=-1Ungültiger Bereich400 Bad Request
?sort=geheimUnbekanntes Sortierfeld400 Bad Request
/produkte/9999Produkt nicht gefunden404 Not Found

Mini-Übungen

Übung 1: URL lesen

Erkläre die Anfrage:

GET /kunden?ort=Berlin&sort=nachname&order=asc&page=2&limit=25
Musterlösung anzeigen

Es werden Kunden aus Berlin abgefragt. Die Liste wird nach Nachname aufsteigend sortiert. Zurückgegeben wird Seite 2 mit maximal 25 Einträgen.

Übung 2: Fehler erkennen

Welche Antwort passt zu dieser Anfrage?

GET /produkte?page=zwei&limit=10
Musterlösung anzeigen

400 Bad Request, weil page eine Zahl sein sollte. Eine verständliche Fehlermeldung sollte den Parameter und den erhaltenen Wert nennen.

Übung 3: Anfrage formulieren

Formuliere eine Anfrage für aktive Zubehör-Produkte, sortiert nach Preis aufsteigend, Seite 1, maximal 10 Einträge.

Musterlösung anzeigen
GET /produkte?kategorie=zubehoer&aktiv=true&sort=preis&order=asc&page=1&limit=10

Checkliste für eigene API-Abfragen

FrageBeispiel
Welche Ressource wird abgefragt?/produkte, /kunden, /bestellungen
Wird ein einzelner Datensatz oder eine Liste benötigt?/produkte/3 oder /produkte
Welche Filter sind nötig??aktiv=true&kategorie=hardware
Welche Sortierung ist sinnvoll?sort=preis&order=desc
Wie viele Daten sollen pro Anfrage kommen?page=1&limit=20
Was passiert bei ungültigen Werten?400 Bad Request mit verständlicher Fehlerantwort